SGI Freeware 2002 November

home *** CD-ROM | disk | FTP | other *** search

/ SGI Freeware 2002 November / SGI Freeware 2002 November - Disc 3.iso / dist / fw_texinfo.idb / usr / freeware / info / texinfo-3.z / texinfo-3

Wrap

Text File | 2001-07-06 | 51KB | 1,288 lines

This is texinfo, produced by makeinfo version 4.0 from texinfo.txi. INFO-DIR-SECTION Texinfo documentation system START-INFO-DIR-ENTRY * Texinfo: (texinfo). The GNU documentation format. * install-info: (texinfo)Invoking install-info. Update info/dir entries. * texi2dvi: (texinfo)Format with texi2dvi. Print Texinfo documents. * texindex: (texinfo)Format with tex/texindex. Sort Texinfo index files. * makeinfo: (texinfo)makeinfo Preferred. Translate Texinfo source. END-INFO-DIR-ENTRY This file documents Texinfo, a documentation system that can produce both online information and a printed manual from a single source file. Copyright (C) 1988, 90, 91, 92, 93, 95, 96, 97, 98, 99 Free Software Foundation, Inc. This edition is for Texinfo version 4.0, 28 September 1999. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. File: texinfo, Node: setfilename, Next: settitle, Prev: Start of Header, Up: Header `@setfilename' -------------- In order to serve as the primary input file for either `makeinfo' or TeX, a Texinfo file must contain a line that looks like this: @setfilename INFO-FILE-NAME Write the `@setfilename' command at the beginning of a line and follow it on the same line by the Info file name. Do not write anything else on the line; anything on the line after the command is considered part of the file name, including what would otherwise be a comment. The `@setfilename' line specifies the name of the output file to be generated. This name should be different from the name of the Texinfo file. There are two conventions for choosing the name: you can either remove the extension (such as `.texi') from the input file name, or replace it with the `.info' extension. When producing HTML output, `makeinfo' will replace any extension with `html', or add `.html' if the given name has no extension. Some operating systems cannot handle long file names. You can run into a problem even when the file name you specify is itself short enough. This occurs because the Info formatters split a long Info file into short indirect subfiles, and name them by appending `-1', `-2', ..., `-10', `-11', and so on, to the original file name. (*Note Tag Files and Split Files: Tag and Split Files.) The subfile name `texinfo.info-10', for example, is too long for some systems; so the Info file name for this document is `texinfo' rather than `texinfo.info'. When `makeinfo' is running on operating systems such as MS-DOS which impose grave limits on file names, it will sometimes remove some characters from the original file name to leave enough space for the subfile suffix, thus producing files named `texin-10', `gcc.i12', etc. The Info formatting commands ignore everything written before the `@setfilename' line, which is why the very first line of the file (the `\input' line) does not show up in the output. The `@setfilename' line produces no output when you typeset a manual with TeX, but it is nevertheless essential: it opens the index, cross-reference, and other auxiliary files used by Texinfo, and also reads `texinfo.cnf' if that file is present on your system (*note Preparing for TeX: Preparing for TeX.). File: texinfo, Node: settitle, Next: setchapternewpage, Prev: setfilename, Up: Header `@settitle' ----------- In order to be made into a printed manual, a Texinfo file must contain a line that looks like this: @settitle TITLE Write the `@settitle' command at the beginning of a line and follow it on the same line by the title. This tells TeX the title to use in a header or footer. Do not write anything else on the line; anything on the line after the command is considered part of the title, including a comment. Conventionally, when TeX formats a Texinfo file for double-sided output, the title is printed in the left-hand (even-numbered) page headings and the current chapter title is printed in the right-hand (odd-numbered) page headings. (TeX learns the title of each chapter from each `@chapter' command.) Page footers are not printed. Even if you are printing in a single-sided style, TeX looks for an `@settitle' command line, in case you include the manual title in the heading. The `@settitle' command should precede everything that generates actual output in TeX. Although the title in the `@settitle' command is usually the same as the title on the title page, it does not affect the title as it appears on the title page. Thus, the two do not need not match exactly; and the title in the `@settitle' command can be a shortened or expanded version of the title as it appears on the title page. (*Note `@titlepage': titlepage.) TeX prints page headings only for that text that comes after the `@end titlepage' command in the Texinfo file, or that comes after an `@headings' command that turns on headings. (*Note The `@headings' Command: headings on off, for more information.) You may, if you wish, create your own, customized headings and footings. *Note Page Headings: Headings, for a detailed discussion of this process. File: texinfo, Node: setchapternewpage, Next: paragraphindent, Prev: settitle, Up: Header `@setchapternewpage' -------------------- In an officially bound book, text is usually printed on both sides of the paper, chapters start on right-hand pages, and right-hand pages have odd numbers. But in short reports, text often is printed only on one side of the paper. Also in short reports, chapters sometimes do not start on new pages, but are printed on the same page as the end of the preceding chapter, after a small amount of vertical whitespace. You can use the `@setchapternewpage' command with various arguments to specify how TeX should start chapters and whether it should format headers for printing on one or both sides of the paper (single-sided or double-sided printing). Write the `@setchapternewpage' command at the beginning of a line followed by its argument. For example, you would write the following to cause each chapter to start on a fresh odd-numbered page: @setchapternewpage odd You can specify one of three alternatives with the `@setchapternewpage' command: `@setchapternewpage off' Cause TeX to typeset a new chapter on the same page as the last chapter, after skipping some vertical whitespace. Also, cause TeX to format page headers for single-sided printing. (You can override the headers format with the `@headings double' command; see *Note The `@headings' Command: headings on off.) `@setchapternewpage on' Cause TeX to start new chapters on new pages and to format page headers for single-sided printing. This is the form most often used for short reports or personal printing. This alternative is the default. `@setchapternewpage odd' Cause TeX to start new chapters on new, odd-numbered pages (right-handed pages) and to typeset for double-sided printing. This is the form most often used for books and manuals. Texinfo does not have an `@setchapternewpage even' command. You can countermand or modify the effect on headers of an `@setchapternewpage' command with an `@headings' command. *Note The `@headings' Command: headings on off. At the beginning of a manual or book, pages are not numbered--for example, the title and copyright pages of a book are not numbered. By convention, table of contents pages are numbered with roman numerals and not in sequence with the rest of the document. Since an Info file does not have pages, the `@setchapternewpage' command has no effect on it. We recommend not including any `@setchapternewpage' command in your manual sources at all, since the desired output is not intrinsic to the document. Instead, if you don't want the default option (no blank pages, same headers on all pages) use the `--texinfo' option to `texi2dvi' to specify the output you want. File: texinfo, Node: paragraphindent, Next: exampleindent, Prev: setchapternewpage, Up: Header Paragraph Indenting ------------------- The Texinfo processors may insert whitespace at the beginning of the first line of each paragraph, thereby indenting that paragraph. You can use the `@paragraphindent' command to specify this indentation. Write an `@paragraphindent' command at the beginning of a line followed by either `asis' or a number: @paragraphindent INDENT The indentation is according to the value of INDENT: `asis' Do not change the existing indentation (not implemented in TeX). 0 Omit all indentation. N Indent by N space characters in Info output, by N ems in TeX. The default value of INDENT is `asis'. `@paragraphindent' is ignored for HTML output. Write the `@paragraphindent' command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you write the command between the start-of-header and end-of-header lines, the region formatting commands indent paragraphs as specified.) A peculiarity of the `texinfo-format-buffer' and `texinfo-format-region' commands is that they do not indent (nor fill) paragraphs that contain `@w' or `@*' commands. *Note Refilling Paragraphs::, for further information. File: texinfo, Node: exampleindent, Next: End of Header, Prev: paragraphindent, Up: Header `@exampleindent': Environment Indenting --------------------------------------- The Texinfo processors indent each line of `@example' and similar environments. You can use the `@exampleindent' command to specify this indentation. Write an `@exampleindent' command at the beginning of a line followed by either `asis' or a number: @exampleindent INDENT The indentation is according to the value of INDENT: `asis' Do not change the existing indentation (not implemented in TeX). 0 Omit all indentation. N Indent environments by N space characters in Info output, by N ems in TeX. The default value of INDENT is 5. `@exampleindent' is ignored for HTML output. Write the `@exampleindent' command before or shortly after the end-of-header line at the beginning of a Texinfo file. (If you write the command between the start-of-header and end-of-header lines, the region formatting commands indent examples as specified.) File: texinfo, Node: End of Header, Prev: exampleindent, Up: Header End of Header ------------- Follow the header lines with an end-of-header line. An end-of-header line looks like this: @c %**end of header If you include the `@setchapternewpage' command between the start-of-header and end-of-header lines, TeX will typeset a region as that command specifies. Similarly, if you include an `@smallbook' command between the start-of-header and end-of-header lines, TeX will typeset a region in the "small" book format. The reason for the odd string of characters (`%**') is so that the `texinfo-tex-region' command does not accidentally find something that it should not when it is looking for the header. The start-of-header line and the end-of-header line are Texinfo mode variables that you can change. File: texinfo, Node: Info Summary and Permissions, Next: Titlepage & Copyright Page, Prev: Header, Up: Beginning a File Summary and Copying Permissions for Info ======================================== The title page and the copyright page appear only in the printed copy of the manual; therefore, the same information must be inserted in a section that appears only in the Info file. This section usually contains a brief description of the contents of the Info file, a copyright notice, and copying permissions. The copyright notice should read: Copyright YEAR COPYRIGHT-OWNER and be put on a line by itself. Standard text for the copyright permissions is contained in an appendix to this manual; see *Note `ifinfo' Copying Permissions: ifinfo Permissions, for the complete text. The permissions text appears in an Info file _before_ the first node. This mean that a reader does _not_ see this text when reading the file using Info, except when using the advanced Info command `g *'. File: texinfo, Node: Titlepage & Copyright Page, Next: The Top Node, Prev: Info Summary and Permissions, Up: Beginning a File The Title and Copyright Pages ============================= A manual's name and author are usually printed on a title page. Sometimes copyright information is printed on the title page as well; more often, copyright information is printed on the back of the title page. The title and copyright pages appear in the printed manual, but not in the Info file. Because of this, it is possible to use several slightly obscure TeX typesetting commands that cannot be used in an Info file. In addition, this part of the beginning of a Texinfo file contains the text of the copying permissions that will appear in the printed manual. You may wish to include titlepage-like information for plain text output. Simply place any such leading material between `@ifinfo' and `@end ifinfo'; `makeinfo' includes this in its plain text output. It will not show up in the Info readers. *Note Titlepage Copying Permissions: Titlepage Permissions, for the standard text for the copyright permissions. * Menu: * titlepage:: Create a title for the printed document. * titlefont center sp:: The `@titlefont', `@center', and `@sp' commands. * title subtitle author:: The `@title', `@subtitle', and `@author' commands. * Copyright & Permissions:: How to write the copyright notice and include copying permissions. * end titlepage:: Turn on page headings after the title and copyright pages. * headings on off:: An option for turning headings on and off and double or single sided printing. File: texinfo, Node: titlepage, Next: titlefont center sp, Prev: Titlepage & Copyright Page, Up: Titlepage & Copyright Page `@titlepage' ------------ Start the material for the title page and following copyright page with `@titlepage' on a line by itself and end it with `@end titlepage' on a line by itself. The `@end titlepage' command starts a new page and turns on page numbering. (*Note Page Headings: Headings, for details about how to generate page headings.) All the material that you want to appear on unnumbered pages should be put between the `@titlepage' and `@end titlepage' commands. You can force the table of contents to appear there with the `@setcontentsaftertitlepage' command (*note Contents::). By using the `@page' command you can force a page break within the region delineated by the `@titlepage' and `@end titlepage' commands and thereby create more than one unnumbered page. This is how the copyright page is produced. (The `@titlepage' command might perhaps have been better named the `@titleandadditionalpages' command, but that would have been rather long!) When you write a manual about a computer program, you should write the version of the program to which the manual applies on the title page. If the manual changes more frequently than the program or is independent of it, you should also include an edition number(1) (*note titlepage-Footnote-1::) for the manual. This helps readers keep track of which manual is for which version of the program. (The `Top' node should also contain this information; see *Note `@top': makeinfo top.) Texinfo provides two main methods for creating a title page. One method uses the `@titlefont', `@sp', and `@center' commands to generate a title page in which the words on the page are centered. The second method uses the `@title', `@subtitle', and `@author' commands to create a title page with black rules under the title and author lines and the subtitle text set flush to the right hand side of the page. With this method, you do not specify any of the actual formatting of the title page. You specify the text you want, and Texinfo does the formatting. You may use either method, or you may combine them; see the examples in the sections below. For extremely simple applications, and for the bastard title page in traditional book front matter, Texinfo also provides a command `@shorttitlepage' which takes a single argument as the title. The argument is typeset on a page by itself and followed by a blank page. File: texinfo, Node: titlepage-Footnotes, Up: titlepage (1) We have found that it is helpful to refer to versions of manuals as `editions' and versions of programs as `versions'; otherwise, we find we are liable to confuse each other in conversation by referring to both the documentation and the software with the same words. File: texinfo, Node: titlefont center sp, Next: title subtitle author, Prev: titlepage, Up: Titlepage & Copyright Page `@titlefont', `@center', and `@sp' ---------------------------------- You can use the `@titlefont', `@sp', and `@center' commands to create a title page for a printed document. (This is the first of the two methods for creating a title page in Texinfo.) Use the `@titlefont' command to select a large font suitable for the title itself. You can use `@titlefont' more than once if you have an especially long title. For example: @titlefont{Texinfo} Use the `@center' command at the beginning of a line to center the remaining text on that line. Thus, @center @titlefont{Texinfo} centers the title, which in this example is "Texinfo" printed in the title font. Use the `@sp' command to insert vertical space. For example: @sp 2 This inserts two blank lines on the printed page. (*Note `@sp': sp, for more information about the `@sp' command.) A template for this method looks like this: @titlepage @sp 10 @center @titlefont{NAME-OF-MANUAL-WHEN-PRINTED} @sp 2 @center SUBTITLE-IF-ANY @sp 2 @center AUTHOR ... @end titlepage The spacing of the example fits an 8.5 by 11 inch manual. File: texinfo, Node: title subtitle author, Next: Copyright & Permissions, Prev: titlefont center sp, Up: Titlepage & Copyright Page `@title', `@subtitle', and `@author' ------------------------------------ You can use the `@title', `@subtitle', and `@author' commands to create a title page in which the vertical and horizontal spacing is done for you automatically. This contrasts with the method described in the previous section, in which the `@sp' command is needed to adjust vertical spacing. Write the `@title', `@subtitle', or `@author' commands at the beginning of a line followed by the title, subtitle, or author. The `@title' command produces a line in which the title is set flush to the left-hand side of the page in a larger than normal font. The title is underlined with a black rule. Only a single line is allowed; the `@*' command may not be used to break the title into two lines. To handle very long titles, you may find it profitable to use both `@title' and `@titlefont'; see the final example in this section. The `@subtitle' command sets subtitles in a normal-sized font flush to the right-hand side of the page. The `@author' command sets the names of the author or authors in a middle-sized font flush to the left-hand side of the page on a line near the bottom of the title page. The names are underlined with a black rule that is thinner than the rule that underlines the title. (The black rule only occurs if the `@author' command line is followed by an `@page' command line.) There are two ways to use the `@author' command: you can write the name or names on the remaining part of the line that starts with an `@author' command: @author by Jane Smith and John Doe or you can write the names one above each other by using two (or more) `@author' commands: @author Jane Smith @author John Doe (Only the bottom name is underlined with a black rule.) A template for this method looks like this: @titlepage @title NAME-OF-MANUAL-WHEN-PRINTED @subtitle SUBTITLE-IF-ANY @subtitle SECOND-SUBTITLE @author AUTHOR @page ... @end titlepage You may also combine the `@titlefont' method described in the previous section and `@title' method described in this one. This may be useful if you have a very long title. Here is a real-life example: @titlepage @titlefont{GNU Software} @sp 1 @title for MS-Windows and MS-DOS @subtitle Edition @value{edition} for Release @value{cd-edition} @author by Daniel Hagerty, Melissa Weisshaus @author and Eli Zaretskii (The use of `@value' here is explained in *Note `@value' Example: value Example.) File: texinfo, Node: Copyright & Permissions, Next: end titlepage, Prev: title subtitle author, Up: Titlepage & Copyright Page Copyright Page and Permissions ------------------------------ By international treaty, the copyright notice for a book should be either on the title page or on the back of the title page. The copyright notice should include the year followed by the name of the organization or person who owns the copyright. When the copyright notice is on the back of the title page, that page is customarily not numbered. Therefore, in Texinfo, the information on the copyright page should be within `@titlepage' and `@end titlepage' commands. Use the `@page' command to cause a page break. To push the copyright notice and the other text on the copyright page towards the bottom of the page, you can write a somewhat mysterious line after the `@page' command that reads like this: @vskip 0pt plus 1filll This is a TeX command that is not supported by the Info formatting commands. The `@vskip' command inserts whitespace. The `0pt plus 1filll' means to put in zero points of mandatory whitespace, and as much optional whitespace as needed to push the following text to the bottom of the page. Note the use of three `l's in the word `filll'; this is the correct usage in TeX. In a printed manual, the `@copyright{}' command generates a `c' inside a circle. (In Info, it generates `(C)'.) The copyright notice itself has the following legally defined sequence: Copyright (C) YEAR COPYRIGHT-OWNER It is customary to put information on how to get a manual after the copyright notice, followed by the copying permissions for the manual. Permissions must be given here as well as in the summary segment within `@ifinfo' and `@end ifinfo' that immediately follows the header since this text appears only in the printed manual and the `ifinfo' text appears only in the Info file. *Note Sample Permissions::, for the standard text. File: texinfo, Node: end titlepage, Next: headings on off, Prev: Copyright & Permissions, Up: Titlepage & Copyright Page Heading Generation ------------------ An `@end titlepage' command on a line by itself not only marks the end of the title and copyright pages, but also causes TeX to start generating page headings and page numbers. To repeat what is said elsewhere, Texinfo has two standard page heading formats, one for documents which are printed on one side of each sheet of paper (single-sided printing), and the other for documents which are printed on both sides of each sheet (double-sided printing). (*Note `@setchapternewpage': setchapternewpage.) You can specify these formats in different ways: * The conventional way is to write an `@setchapternewpage' command before the title page commands, and then have the `@end titlepage' command start generating page headings in the manner desired. (*Note `@setchapternewpage': setchapternewpage.) * Alternatively, you can use the `@headings' command to prevent page headings from being generated or to start them for either single or double-sided printing. (Write an `@headings' command immediately after the `@end titlepage' command. *Note The `@headings' Command: headings on off, for more information.) * Or, you may specify your own page heading and footing format. *Note Page Headings: Headings, for detailed information about page headings and footings. Most documents are formatted with the standard single-sided or double-sided format, using `@setchapternewpage odd' for double-sided printing and no `@setchapternewpage' command for single-sided printing. File: texinfo, Node: headings on off, Prev: end titlepage, Up: Titlepage & Copyright Page The `@headings' Command ----------------------- The `@headings' command is rarely used. It specifies what kind of page headings and footings to print on each page. Usually, this is controlled by the `@setchapternewpage' command. You need the `@headings' command only if the `@setchapternewpage' command does not do what you want, or if you want to turn off pre-defined page headings prior to defining your own. Write an `@headings' command immediately after the `@end titlepage' command. You can use `@headings' as follows: `@headings off' Turn off printing of page headings. `@headings single' Turn on page headings appropriate for single-sided printing. `@headings double' `@headings on' Turn on page headings appropriate for double-sided printing. The two commands, `@headings on' and `@headings double', are synonymous. `@headings singleafter' `@headings doubleafter' Turn on `single' or `double' headings, respectively, after the current page is output. `@headings on' Turn on page headings: `single' if `@setchapternewpage on', `double' otherwise. For example, suppose you write `@setchapternewpage off' before the `@titlepage' command to tell TeX to start a new chapter on the same page as the end of the last chapter. This command also causes TeX to typeset page headers for single-sided printing. To cause TeX to typeset for double sided printing, write `@headings double' after the `@end titlepage' command. You can stop TeX from generating any page headings at all by writing `@headings off' on a line of its own immediately after the line containing the `@end titlepage' command, like this: @end titlepage @headings off The `@headings off' command overrides the `@end titlepage' command, which would otherwise cause TeX to print page headings. You can also specify your own style of page heading and footing. *Note Page Headings: Headings, for more information. File: texinfo, Node: The Top Node, Next: Software Copying Permissions, Prev: Titlepage & Copyright Page, Up: Beginning a File The `Top' Node and Master Menu ============================== The `Top' node is the node from which you enter an Info file. A `Top' node should contain a brief description of the Info file and an extensive, master menu for the whole Info file. This helps the reader understand what the Info file is about. Also, you should write the version number of the program to which the Info file applies; or, at least, the edition number. The contents of the `Top' node should appear only in the Info file; none of it should appear in printed output, so enclose it between `@ifinfo' and `@end ifinfo' commands. (TeX does not print either an `@node' line or a menu; they appear only in Info; strictly speaking, you are not required to enclose these parts between `@ifinfo' and `@end ifinfo', but it is simplest to do so. *Note Conditionally Visible Text: Conditionals.) * Menu: * Title of Top Node:: Sketch what the file is about. * Master Menu Parts:: A master menu has three or more parts. File: texinfo, Node: Title of Top Node, Next: Master Menu Parts, Up: The Top Node `Top' Node Title ---------------- Sometimes, you will want to place an `@top' sectioning command line containing the title of the document immediately after the `@node Top' line (*note The `@top' Sectioning Command: makeinfo top command., for more information). For example, the beginning of the Top node of this manual contains an `@top' sectioning command, a short description, and edition and version information. It looks like this: ... @end titlepage @ifnottex @node Top, Copying, , (dir) @top Texinfo Texinfo is a documentation system... This is edition... ... @end ifnottex @menu * Copying:: Texinfo is freely redistributable. * Overview:: What is Texinfo? ... @end menu In a `Top' node, the `Previous', and `Up' nodes usually refer to the top level directory of the whole Info system, which is called `(dir)'. The `Next' node refers to the first node that follows the main or master menu, which is usually the copying permissions, introduction, or first chapter. File: texinfo, Node: Master Menu Parts, Prev: Title of Top Node, Up: The Top Node Parts of a Master Menu ---------------------- A "master menu" is a detailed main menu listing all the nodes in a file. A master menu is enclosed in `@menu' and `@end menu' commands and does not appear in the printed document. Generally, a master menu is divided into parts. * The first part contains the major nodes in the Texinfo file: the nodes for the chapters, chapter-like sections, and the appendices. * The second part contains nodes for the indices. * The third and subsequent parts contain a listing of the other, lower level nodes, often ordered by chapter. This way, rather than go through an intermediary menu, an inquirer can go directly to a particular node when searching for specific information. These menu items are not required; add them if you think they are a convenience. If you do use them, put `@detailmenu' before the first one, and `@end detailmenu' after the last; otherwise, `makeinfo' will get confused. Each section in the menu can be introduced by a descriptive line. So long as the line does not begin with an asterisk, it will not be treated as a menu entry. (*Note Writing a Menu::, for more information.) For example, the master menu for this manual looks like the following (but has many more entries): @menu * Copying:: Texinfo is freely redistributable. * Overview:: What is Texinfo? * Texinfo Mode:: Special features in GNU Emacs. ... ... * Command and Variable Index:: An entry for each @-command. * Concept Index:: An entry for each concept. @detailmenu --- The Detailed Node Listing --- Overview of Texinfo * Info Files:: What is an Info file? * Printed Manuals:: Characteristics of a printed manual. ... ... Using Texinfo Mode * Info on a Region:: Formatting part of a file for Info. ... ... @end detailmenu @end menu File: texinfo, Node: Software Copying Permissions, Prev: The Top Node, Up: Beginning a File Software Copying Permissions ============================ If the Texinfo file has a section containing the "General Public License" and the distribution information and a warranty disclaimer for the software that is documented, this section usually follows the `Top' node. The General Public License is very important to Project GNU software. It ensures that you and others will continue to have a right to use and share the software. The copying and distribution information and the disclaimer are followed by an introduction or else by the first chapter of the manual. Although an introduction is not a required part of a Texinfo file, it is very helpful. Ideally, it should state clearly and concisely what the file is about and who would be interested in reading it. In general, an introduction would follow the licensing and distribution information, although sometimes people put it earlier in the document. Usually, an introduction is put in an `@unnumbered' section. (*Note The `@unnumbered' and `@appendix' Commands: unnumbered & appendix.) File: texinfo, Node: Ending a File, Next: Structuring, Prev: Beginning a File, Up: Top Ending a Texinfo File ********************* The end of a Texinfo file should include commands to create indices and (usually) to generate detailed and summary tables of contents. And it must include the `@bye' command that marks the last line processed by TeX. For example: @node Concept Index, , Variables Index, Top @c node-name, next, previous, up @unnumbered Concept Index @printindex cp @contents @bye * Menu: * Printing Indices & Menus:: How to print an index in hardcopy and generate index menus in Info. * Contents:: How to create a table of contents. * File End:: How to mark the end of a file. File: texinfo, Node: Printing Indices & Menus, Next: Contents, Prev: Ending a File, Up: Ending a File Index Menus and Printing an Index ================================= To print an index means to include it as part of a manual or Info file. This does not happen automatically just because you use `@cindex' or other index-entry generating commands in the Texinfo file; those just cause the raw data for the index to be accumulated. To generate an index, you must include the `@printindex' command at the place in the document where you want the index to appear. Also, as part of the process of creating a printed manual, you must run a program called `texindex' (*note Hardcopy::) to sort the raw data to produce a sorted index file. The sorted index file is what is actually used to print the index. Texinfo offers six different types of predefined index: the concept index, the function index, the variables index, the keystroke index, the program index, and the data type index (*note Predefined Indices::). Each index type has a two-letter name: `cp', `fn', `vr', `ky', `pg', and `tp'. You may merge indices, or put them into separate sections (*note Combining Indices::); or you may define your own indices (*note Defining New Indices: New Indices.). The `@printindex' command takes a two-letter index name, reads the corresponding sorted index file and formats it appropriately into an index. The `@printindex' command does not generate a chapter heading for the index. Consequently, you should precede the `@printindex' command with a suitable section or chapter command (usually `@unnumbered') to supply the chapter heading and put the index into the table of contents. Precede the `@unnumbered' command with an `@node' line. For example: @node Variable Index, Concept Index, Function Index, Top @comment node-name, next, previous, up @unnumbered Variable Index @printindex vr @node Concept Index, , Variable Index, Top @comment node-name, next, previous, up @unnumbered Concept Index @printindex cp Readers often prefer that the concept index come last in a book, since that makes it easiest to find. Having just one index helps readers also, since then they have only one place to look (*note synindex::). File: texinfo, Node: Contents, Next: File End, Prev: Printing Indices & Menus, Up: Ending a File Generating a Table of Contents ============================== The `@chapter', `@section', and other structuring commands supply the information to make up a table of contents, but they do not cause an actual table to appear in the manual. To do this, you must use the `@contents' and/or `@summarycontents' command(s). `@contents' Generate a table of contents in a printed manual, including all chapters, sections, subsections, etc., as well as appendices and unnumbered chapters. (Headings generated by the `@heading' series of commands do not appear in the table of contents.) `@shortcontents' `@summarycontents' (`@summarycontents' is a synonym for `@shortcontents'; the two commands are exactly the same.) Generate a short or summary table of contents that lists only the chapters (and appendices and unnumbered chapters). Omit sections, subsections and subsubsections. Only a long manual needs a short table of contents in addition to the full table of contents. Both contents commands should be written on a line by themselves. The contents commands automatically generate a chapter-like heading at the top of the first table of contents page, so don't include any sectioning command such as `@unnumbered' before them. Since an Info file uses menus instead of tables of contents, the Info formatting commands ignore the contents commands. But the contents are included in plain text output (generated by `makeinfo --no-headers'). The contents commands can be placed either at the very end of the file, after any indices (see the previous section) and just before the `@bye' (see the next section), or near the beginning of the file, after the `@end titlepage' (*note titlepage::). The advantage to the former is that then the contents output is always up to date, because it reflects the processing just done. The advantage to the latter is that the contents are printed in the proper place, thus you do not need to rearrange the DVI file with `dviselect' or shuffle paper. However, contents commands at the beginning of the document are ignored when outputting to standard output. As an author, you can put the contents commands wherever you prefer. But if you are a user simply printing a manual, you may wish to print the contents after the title page even if the author put the contents commands at the end of the document (as is the case in most existing Texinfo documents). You can do this by specifying `@setcontentsaftertitlepage' and/or `@setshortcontentsaftertitlepage'. The first prints only the main contents after the `@end titlepage'; the second prints both the short contents and the main contents. In either case, any subsequent `@contents' or `@shortcontents' is ignored (unless no `@end titlepage' is ever encountered). You need to include the `@set...contentsaftertitlepage' commands early in the document (just after `@setfilename', for example). Or, if you're using `texi2dvi' (*note Format with texi2dvi::), you can use its `--texinfo' option to specify this without altering the source file at all. For example: texi2dvi --texinfo=@setshortcontentsaftertitlepage foo.texi File: texinfo, Node: File End, Prev: Contents, Up: Ending a File `@bye' File Ending ================== An `@bye' command terminates TeX or Info formatting. None of the formatting commands see any of the file following `@bye'. The `@bye' command should be on a line by itself. If you wish, you may follow the `@bye' line with notes. These notes will not be formatted and will not appear in either Info or a printed manual; it is as if text after `@bye' were within `@ignore' ... `@end ignore'. Also, you may follow the `@bye' line with a local variables list. *Note Using Local Variables and the Compile Command: Compile-Command, for more information. File: texinfo, Node: Structuring, Next: Nodes, Prev: Ending a File, Up: Top Chapter Structuring ******************* The "chapter structuring" commands divide a document into a hierarchy of chapters, sections, subsections, and subsubsections. These commands generate large headings; they also provide information for the table of contents of a printed manual (*note Generating a Table of Contents: Contents.). The chapter structuring commands do not create an Info node structure, so normally you should put an `@node' command immediately before each chapter structuring command (*note Nodes::). The only time you are likely to use the chapter structuring commands without using the node structuring commands is if you are writing a document that contains no cross references and will never be transformed into Info format. It is unlikely that you will ever write a Texinfo file that is intended only as an Info file and not as a printable document. If you do, you might still use chapter structuring commands to create a heading at the top of each node--but you don't need to. * Menu: * Tree Structuring:: A manual is like an upside down tree ... * Structuring Command Types:: How to divide a manual into parts. * makeinfo top:: The `@top' command, part of the `Top' node. * chapter:: * unnumbered & appendix:: * majorheading & chapheading:: * section:: * unnumberedsec appendixsec heading:: * subsection:: * unnumberedsubsec appendixsubsec subheading:: * subsubsection:: Commands for the lowest level sections. * Raise/lower sections:: How to change commands' hierarchical level. File: texinfo, Node: Tree Structuring, Next: Structuring Command Types, Up: Structuring Tree Structure of Sections ========================== A Texinfo file is usually structured like a book with chapters, sections, subsections, and the like. This structure can be visualized as a tree (or rather as an upside-down tree) with the root at the top and the levels corresponding to chapters, sections, subsection, and subsubsections. Here is a diagram that shows a Texinfo file with three chapters, each of which has two sections. Top | ------------------------------------- | | | Chapter 1 Chapter 2 Chapter 3 | | | -------- -------- -------- | | | | | | Section Section Section Section Section Section 1.1 1.2 2.1 2.2 3.1 3.2 In a Texinfo file that has this structure, the beginning of Chapter 2 looks like this: @node Chapter 2, Chapter 3, Chapter 1, top @chapter Chapter 2 The chapter structuring commands are described in the sections that follow; the `@node' and `@menu' commands are described in following chapters. (*Note Nodes::, and see *Note Menus::.) File: texinfo, Node: Structuring Command Types, Next: makeinfo top, Prev: Tree Structuring, Up: Structuring Structuring Command Types ========================= The chapter structuring commands fall into four groups or series, each of which contains structuring commands corresponding to the hierarchical levels of chapters, sections, subsections, and subsubsections. The four groups are the `@chapter' series, the `@unnumbered' series, the `@appendix' series, and the `@heading' series. Each command produces titles that have a different appearance on the printed page or Info file; only some of the commands produce titles that are listed in the table of contents of a printed book or manual. * The `@chapter' and `@appendix' series of commands produce numbered or lettered entries both in the body of a printed work and in its table of contents. * The `@unnumbered' series of commands produce unnumbered entries both in the body of a printed work and in its table of contents. The `@top' command, which has a special use, is a member of this series (*note `@top': makeinfo top.). * The `@heading' series of commands produce unnumbered headings that do not appear in a table of contents. The heading commands never start a new page. * The `@majorheading' command produces results similar to using the `@chapheading' command but generates a larger vertical whitespace before the heading. * When an `@setchapternewpage' command says to do so, the `@chapter', `@unnumbered', and `@appendix' commands start new pages in the printed manual; the `@heading' commands do not. Here are the four groups of chapter structuring commands: No new page Numbered Unnumbered Lettered and numbered Unnumbered In contents In contents In contents Not in contents `@top' `@majorheading' `@chapter' `@unnumbered' `@appendix' `@chapheading' `@section' `@unnumberedsec' `@appendixsec' `@heading' `@subsection' `@unnumberedsubsec' `@appendixsubsec' `@subheading' `@subsubsection'`@unnumberedsubsubsec' `@appendixsubsubsec' `@subsubheading' File: texinfo, Node: makeinfo top, Next: chapter, Prev: Structuring Command Types, Up: Structuring `@top' ====== The `@top' command is a special sectioning command that you use only after an `@node Top' line at the beginning of a Texinfo file. The `@top' command tells the `makeinfo' formatter which node is the `Top' node, so it can use it as the root of the node tree if your manual uses implicit pointers. It has the same typesetting effect as `@unnumbered' (*note `@unnumbered' and `@appendix': unnumbered & appendix.). For detailed information, see *Note The `@top' Command: makeinfo top command. The `@top' node and its menu (if any) is conventionally wrapped in an `@ifnottex' conditional so that it will appear only in Info and HTML output, not TeX. File: texinfo, Node: chapter, Next: unnumbered & appendix, Prev: makeinfo top, Up: Structuring `@chapter' ========== `@chapter' identifies a chapter in the document. Write the command at the beginning of a line and follow it on the same line by the title of the chapter. For example, this chapter in this manual is entitled "Chapter Structuring"; the `@chapter' line looks like this: @chapter Chapter Structuring In TeX, the `@chapter' command creates a chapter in the document, specifying the chapter title. The chapter is numbered automatically. In Info, the `@chapter' command causes the title to appear on a line by itself, with a line of asterisks inserted underneath. Thus, in Info, the above example produces the following output: Chapter Structuring ******************* Texinfo also provides a command `@centerchap', which is analogous to `@unnumbered', but centers its argument in the printed output. This kind of stylistic choice is not usually offered by Texinfo. File: texinfo, Node: unnumbered & appendix, Next: majorheading & chapheading, Prev: chapter, Up: Structuring `@unnumbered' and `@appendix' ============================= Use the `@unnumbered' command to create a chapter that appears in a printed manual without chapter numbers of any kind. Use the `@appendix' command to create an appendix in a printed manual that is labelled by letter instead of by number. For Info file output, the `@unnumbered' and `@appendix' commands are equivalent to `@chapter': the title is printed on a line by itself with a line of asterisks underneath. (*Note `@chapter': chapter.) To create an appendix or an unnumbered chapter, write an `@appendix' or `@unnumbered' command at the beginning of a line and follow it on the same line by the title, as you would if you were creating a chapter. File: texinfo, Node: majorheading & chapheading, Next: section, Prev: unnumbered & appendix, Up: Structuring `@majorheading', `@chapheading' =============================== The `@majorheading' and `@chapheading' commands put chapter-like headings in the body of a document. However, neither command causes TeX to produce a numbered heading or an entry in the table of contents; and neither command causes TeX to start a new page in a printed manual. In TeX, an `@majorheading' command generates a larger vertical whitespace before the heading than an `@chapheading' command but is otherwise the same. In Info, the `@majorheading' and `@chapheading' commands are equivalent to `@chapter': the title is printed on a line by itself with a line of asterisks underneath. (*Note `@chapter': chapter.) File: texinfo, Node: section, Next: unnumberedsec appendixsec heading, Prev: majorheading & chapheading, Up: Structuring `@section' ========== In a printed manual, an `@section' command identifies a numbered section within a chapter. The section title appears in the table of contents. In Info, an `@section' command provides a title for a segment of text, underlined with `='. This section is headed with an `@section' command and looks like this in the Texinfo file: @section @code{@@section} To create a section, write the `@section' command at the beginning of a line and follow it on the same line by the section title. Thus, @section This is a section produces This is a section ================= in Info. File: texinfo, Node: unnumberedsec appendixsec heading, Next: subsection, Prev: section, Up: Structuring `@unnumberedsec', `@appendixsec', `@heading' ============================================ The `@unnumberedsec', `@appendixsec', and `@heading' commands are, respectively, the unnumbered, appendix-like, and heading-like equivalents of the `@section' command. (*Note `@section': section.) `@unnumberedsec' The `@unnumberedsec' command may be used within an unnumbered chapter or within a regular chapter or appendix to provide an unnumbered section. `@appendixsec' `@appendixsection' `@appendixsection' is a longer spelling of the `@appendixsec' command; the two are synonymous. Conventionally, the `@appendixsec' or `@appendixsection' command is used only within appendices. `@heading' You may use the `@heading' command anywhere you wish for a section-style heading that will not appear in the table of contents. File: texinfo, Node: subsection, Next: unnumberedsubsec appendixsubsec subheading, Prev: unnumberedsec appendixsec heading, Up: Structuring The `@subsection' Command ========================= Subsections are to sections as sections are to chapters. (*Note `@section': section.) In Info, subsection titles are underlined with `-'. For example, @subsection This is a subsection produces This is a subsection -------------------- In a printed manual, subsections are listed in the table of contents and are numbered three levels deep.